ESQL: Timezone query setting and added to the query config #136205

ivancea · 2025-10-08T15:48:09Z

This PR covers until right before the query setting is accessible from the Configuration.

PR roadmap

Convert the query settings into something similar to the cluster setting objects, having an automatic parser to convert them to values and so on (Example)
- Reusing those classes look not too straightforward, as we use ESQL Expressions, not strings
- Add a parser and a default value. Because they're generic, I had to transform the enum into static fields
- Organize tests to easily add more settings there
(Next PR) Add the values to the Configuration object, with a simple API like configuration.getSetting(QuerySettings.TIME_ZONE)
- Refactored the configuration so it's created after the query parsing
- (Next PR) For that, the QuerySettings class must be visible from wherever it's used, or the constants should be localized in some common place. Check this!
- (Next PR) TransportVersion to share them

github-actions · 2025-10-08T15:49:48Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

…on for it

# Conflicts: # server/src/main/resources/transport/upper_bounds/9.3.csv # x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/EsqlSession.java

alex-spies

First round of comments

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/EsqlSession.java

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/Configuration.java

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

alex-spies · 2025-10-10T10:19:30Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

+        return new QuerySettingsMap(settings);
+    }
+
+    public static class QuerySettingsMap implements Writeable {


nit: The QuerySettings class has become a class without instances. Why not re-use it for the map, rather than having a separate class that holds the map?

Good idea, I'll try to do that (in the next PR)

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

alex-spies · 2025-10-10T10:22:28Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

+
+        private final Map<String, Expression> settings;
+
+        public QuerySettingsMap(Map<String, Expression> settings) {


nit: Any reason for this not being a Map<QuerySettingsDef, Expression>? We could back this with an enum map to avoid looking things up by string.

Currently the Def has validation, parsing... It's similar to Settings, but for ESQL.
I created this class just to be transported to datanodes: Plain data, to be read by datanodes using their Defs.

As I'm removing transport for this PR, I'll rethink a bit those topics

This is fine and the API you made is cool.

But, maybe looking up by string will be a little heavy; the querysettingsdefs are kinda just an enum and could be assigned ids as well.

We could store it in the configuration later as the map you comment yes. Even without IDs, as they're static objects. It would matter at transport time though, but we're free to serialize as strings in there if we want.

So yep, I'll make this change in the next PR!

alex-spies · 2025-10-10T10:30:38Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

+            }
+        }
+
+        public <T> T get(QuerySettingDef<T> def, RemoteClusterService clusterService) {


Having to pass in the RCS every time sounds wrong. Isn't this something that we'd only do once, when the query is first parsed and we read the QuerySetting values from the parsed query?

That is, I'd expect that we use the RCS once while building the QuerySettingsMap, and after, the settings are fixed and passed around.

Otherwise, we'd have to pass the RCS to all functions that might want to get a setting value.

I think the same. Theoretically, it will depend on how we store this in the config: If we store the original Expression, or the final value. This is still a bit abstract, as no actual config uses that yet though, so I'm not sure if this is required here to begin with. I could remove it from get() and keep it only in validate().
@luigidellaquila, some idea of what we need that for?

or the final value
I think we should only store the final (Literal or <T>) value unless there's a good reason for settings to be complex enough that they have a dynamic value that can change where the setting is used. But even then, I think it still should be a final value and whatever is dynamic about it should be retrieved on the node where it's relevant.

I think the flow should be

raw parsing from the query string

validate + parse the actual settings, use RCS or pass in whatever else the settings need to be validated or parsed

store the parsed result in a map that is passed on as part of the config.

alex-spies · 2025-10-10T10:33:12Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

+            "esql_configuration_query_settings"
+        );
+
+        private final Map<String, Expression> settings;


nit: I'd be a little more relaxed if this was restricted to Literals rather than arbitrary expressions ^^" Having an expression as setting sounds more complex than we currently need.

…e added later

elasticsearchmachine · 2025-10-10T11:09:17Z

Pinging @elastic/es-analytical-engine (Team:Analytics)

ivancea · 2025-10-10T11:11:41Z

.../plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plugin/EsqlQueryClusterSettings.java

+
+package org.elasticsearch.xpack.esql.plugin;
+
+public record EsqlQueryClusterSettings(


This is just a bundle of the required cluster settings used by the EsqlSession to create the configuration. We could also pass the cluster settings themselves and let the EsqlSession do it itself, but I wasn't sure if we wanted that. I'll evaluate the change

ivancea · 2025-10-10T11:16:46Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/EsqlSession.java

The major changes here are:

We now don't receive the config nor the optimizers in the constructor

We instead create them in execute()

So, we have to propagate them through methods

ivancea · 2025-10-10T11:18:57Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/EsqlParser.java

The "Configuration" object wasn't being used here, at all. So I removed it. And this led to many changes along tests.
That's good btw, as otherwise creating the config after parsing would have been quite harder

alex-spies

Hey, I think the refactoring is super nice, thank you!

alex-spies · 2025-10-10T10:46:18Z

.../plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plugin/TransportEsqlQueryAction.java

            sessionId,
-            configuration,
-            foldCtx,
+            new EsqlQueryClusterSettings(


Maybe this is more appropriate as name:

Suggested change

new EsqlQueryClusterSettings(

new AnalyzerSettings(

Or QueryTruncationSettings or so.

We also have PlannerSettings that are obtained from the ClusterService.

alex-spies · 2025-10-10T11:19:26Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

+
+        private final Map<String, Expression> settings;
+
+        public QuerySettingsMap(Map<String, Expression> settings) {


This is fine and the API you made is cool.

But, maybe looking up by string will be a little heavy; the querysettingsdefs are kinda just an enum and could be assigned ids as well.

alex-spies · 2025-10-10T11:27:56Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

+            }
+        }
+
+        public <T> T get(QuerySettingDef<T> def, RemoteClusterService clusterService) {


or the final value
I think we should only store the final (Literal or <T>) value unless there's a good reason for settings to be complex enough that they have a dynamic value that can change where the setting is used. But even then, I think it still should be a final value and whatever is dynamic about it should be retrieved on the node where it's relevant.

I think the flow should be

raw parsing from the query string

validate + parse the actual settings, use RCS or pass in whatever else the settings need to be validated or parsed

store the parsed result in a map that is passed on as part of the config.

ivancea added 2 commits October 8, 2025 15:43

ESQL: Added time_zone settings and added parsing to settings

2d627e7

Added defaults to settings

15907af

ivancea requested a review from luigidellaquila October 8, 2025 15:48

ivancea added >non-issue Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) :Analytics/ES|QL AKA ESQL v9.3.0 labels Oct 8, 2025

github-actions bot deployed to docs-preview October 8, 2025 15:48 View deployment

[CI] Auto commit changes from spotless

05129b0

github-actions bot deployed to docs-preview October 8, 2025 15:57 View deployment

WIP: Config refactor, moved to EsqlSession, and added transport versi…

65e332e

…on for it

github-actions bot deployed to docs-preview October 9, 2025 16:01 View deployment

[CI] Auto commit changes from spotless

2dbd374

github-actions bot deployed to docs-preview October 9, 2025 16:08 View deployment

[CI] Update transport version definitions

3f90a9e

github-actions bot deployed to docs-preview October 9, 2025 16:21 View deployment

Merge branch 'main' into esql-timezone-query-setting

098645f

# Conflicts: # server/src/main/resources/transport/upper_bounds/9.3.csv # x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/EsqlSession.java

github-actions bot deployed to docs-preview October 10, 2025 09:54 View deployment

Update tests and benchmarks

f750112

github-actions bot deployed to docs-preview October 10, 2025 10:34 View deployment

alex-spies reviewed Oct 10, 2025

View reviewed changes

Remove TransportVersions change and settings from Configuration. To b…

06391d8

…e added later

github-actions bot deployed to docs-preview October 10, 2025 11:05 View deployment

Make QuerySettings.ALL_SETTINGS a map

deff0a0

github-actions bot had a problem deploying to docs-preview October 10, 2025 11:08 Failure

ivancea marked this pull request as ready for review October 10, 2025 11:08

Merge branch 'main' into esql-timezone-query-setting

38e0d31

Remove removed TV file

8d44bb6

github-actions bot had a problem deploying to docs-preview October 10, 2025 11:09 Failure

github-actions bot deployed to docs-preview October 10, 2025 11:10 View deployment

ivancea commented Oct 10, 2025

View reviewed changes

alex-spies approved these changes Oct 10, 2025

View reviewed changes

Fix test

fdd23af

github-actions bot deployed to docs-preview October 10, 2025 12:31 View deployment

Merge branch 'main' into esql-timezone-query-setting

e395106

github-actions bot deployed to docs-preview October 10, 2025 15:59 View deployment


		private final Map<String, Expression> settings;

		public QuerySettingsMap(Map<String, Expression> settings) {


		package org.elasticsearch.xpack.esql.plugin;

		public record EsqlQueryClusterSettings(

ESQL: Timezone query setting and added to the query config #136205

Are you sure you want to change the base?

ESQL: Timezone query setting and added to the query config #136205

Uh oh!

Conversation

ivancea commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR roadmap

Uh oh!

github-actions bot commented Oct 8, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

alex-spies left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticsearchmachine commented Oct 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alex-spies left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ivancea commented Oct 8, 2025 •

edited

Loading